package net.wanderinghorse.jsonmessage;

/**
 * This interface is used for harvesting out the work
 * of performing the actual post of a Request to a remote dispatcher.
 * What transport it uses is up to the implementation.
 *
 * Implementations are responsible for implementing the post() behaviour
 * of Request objects, i.e. sending them somewhere. The exact semantics
 * and conventions are described in detail in the project's wiki
 * and the library manual.
 */
public interface RequestPoster {
    /**
     * Must behave, insofar as is possible in Java, identically
     * to the JSONMessage.Request.post() interface defined in the
     * JavaScript-side Request API and the library manual.
     *
     * Implementations must document which PostOptions they support (or do not
     * support).
     *
     * Implementations should pay special attention to the conventions regarding
     * the various request callbacks (stored in the opt object). See the
     * LocalRequestPoster and HttpRequestPoster classes for concrete implementations
     * which follow those conventions. The AbstractRequestPoster implementation
     * provides most of the implementation code, and should be subclassed
     * or aggregated when possible, as opposed to doing all of the handling via a custom
     * implementation.
     *
     * Implementations may throw arbitrary unchecked exceptions but are encouraged
     * instead to report errors via the callback mechanism.
     *
     * TODO:?? specify jsonp handling requirements.
     *
     * @param r The request to post.
     * @param opt The connection options to use for the request. It is up to
     * the caller to ensure that all required options are set.
     */
    public void post( Request r, PostOptions opt );
}
